Add tracing support using Micrometer #1695

nhachicha · 2025-04-29T13:33:11Z

https://jira.mongodb.org/browse/JAVA-5733

rozza

I'm liking the approach.

~~Does this meet the spec for transactions and retryable operations?~~

~~I'm hoping so as both OperationContext#withSessionContext and OperationContext#withTimeoutContext reuse the operation id.~~

~~However, it would be worth clarifying before reviewing further.~~

driver-core/src/main/com/mongodb/tracing/MicrometerTracer.java

Copilot

Pull Request Overview

This PR adds comprehensive tracing support to the MongoDB Java driver using Micrometer as the tracing framework. The implementation provides tracing for commands, operations, and transactions with span hierarchies that allow for detailed observability of database interactions.

Integration of Micrometer tracing with a new MicrometerTracer implementation
Command, operation, and transaction span creation with proper parent-child relationships
Cursor tracking to link getMore operations with their originating queries
Test infrastructure including unified test support and utility classes for span validation

Reviewed Changes

Copilot reviewed 45 out of 45 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
gradle/libs.versions.toml	Adds Micrometer tracing dependencies and test bundles
driver-core/src/main/com/mongodb/tracing/MicrometerTracer.java	Main tracer implementation that bridges MongoDB driver with Micrometer
driver-core/src/main/com/mongodb/internal/tracing/TracingManager.java	Core tracing management with span lifecycle and context handling
driver-core/src/main/com/mongodb/internal/connection/InternalStreamConnection.java	Command-level tracing integration with connection handling
driver-sync/src/test/functional/com/mongodb/client/tracing/SpanTree.java	Test utility for validating span hierarchies and structures
Multiple build.gradle.kts files	Dependency updates across driver modules

Comments suppressed due to low confidence (1)

driver-core/src/test/unit/com/mongodb/internal/connection/CommandHelperTest.java:121

[nitpick] Empty line removed unnecessarily. This appears to be an unrelated formatting change that should not be included in a tracing feature PR.

    OperationContext createOperationContext() {

driver-core/src/main/com/mongodb/internal/tracing/package-info.java

Copilot · 2025-07-21T13:27:59Z

driver-core/src/main/com/mongodb/MongoNamespace.java

        notNull("fullName", fullName);
        this.fullName = fullName;
-        this.databaseName = getDatatabaseNameFromFullName(fullName);
+        this.databaseName = getDatabaseNameFromFullName(fullName);


Method name corrected from 'getDatatabaseNameFromFullName' to 'getDatabaseNameFromFullName' - this appears to be an unrelated typo fix that should not be included in a tracing feature PR.

Copilot · 2025-07-21T13:27:59Z

driver-sync/src/test/functional/com/mongodb/client/tracing/SpanTree.java

+    private static void assertValid(final SpanNode reportedNode, final SpanNode expectedNode,
+            final BiConsumer<BsonValue, BsonValue> valueMatcher) {
+        // Check that the span names match
+        if (!reportedNode.getName().equalsIgnoreCase(expectedNode.getName())) {


[nitpick] Using case-insensitive comparison for span names may hide actual mismatches. Consider using exact string comparison unless case variations are explicitly expected.

Suggested change

if (!reportedNode.getName().equalsIgnoreCase(expectedNode.getName())) {

if (!reportedNode.getName().equals(expectedNode.getName())) {

Copilot · 2025-07-21T13:28:00Z

driver-sync/src/test/functional/com/mongodb/client/tracing/SpanTree.java

+                return false;
+            }
+            final SpanNode spanNode = (SpanNode) o;
+            return name.equalsIgnoreCase(spanNode.name)


[nitpick] Inconsistent case handling in equals method. The case-insensitive comparison should match the behavior used in assertValid method, but consider if this is the intended behavior.

rozza

First review - overall looks really good, just a couple of nits.

My main point of contention is: Is an com.mongodb.internal.tracing the correct place? Given that MongoClientSettings accepts a TracingManager that seems against the norm in the code base. Should there be a TracingManager interface along with the other interfaces and then internal implementations of it? eg: TracingManagerImpl

What do you think?

rozza · 2025-07-22T08:38:08Z

driver-core/src/main/com/mongodb/MongoClientSettings.java

+         * @return this
+         * @since 5.5
+         */
+        @Alpha(Reason.CLIENT)


Q: Is this going to be released as alpha?

driver-core/src/main/com/mongodb/internal/connection/CommandMessage.java

driver-core/src/main/com/mongodb/internal/connection/InternalStreamConnection.java

driver-core/src/main/com/mongodb/internal/operation/AggregateOperationImpl.java

driver-scala/build.gradle.kts

driver-sync/src/main/com/mongodb/client/internal/ClientSessionImpl.java

driver-sync/src/test/functional/com/mongodb/client/tracing/ZipkinTracer.java

driver-sync/src/test/functional/com/mongodb/client/unified/Entities.java

jyemin

I did a high level review of the API and the overall design.

driver-core/src/main/com/mongodb/internal/connection/CommandMessage.java

driver-core/src/main/com/mongodb/MongoClientSettings.java

driver-core/src/main/com/mongodb/internal/tracing/TracingManager.java

jyemin · 2025-07-23T20:44:50Z

driver-core/src/main/com/mongodb/internal/tracing/TracingManager.java

+import static java.lang.String.format;
+
+/**
+ * Manages tracing spans for MongoDB driver activities.


I'm not clear why a class like this is necessary. As I understand it, there is a single instance created at the scope of MongoClientSettings, and treated as effectively a singleton by the MongoClient instance. Would it be sufficient, and also simpler, to create a new instance of some class at the point where we start execution of an operation or transaction, and allow it to garbage collected when the operation or transaction completes?

New implementation uses a single instance per MongoClient.

driver-core/src/main/com/mongodb/MongoNamespace.java

driver-sync/src/main/com/mongodb/client/internal/ClientSessionImpl.java

driver-sync/src/main/com/mongodb/client/internal/MongoClientImpl.java

driver-sync/src/main/com/mongodb/client/internal/MongoClusterImpl.java

jyemin · 2025-07-23T21:00:45Z

driver-core/src/main/com/mongodb/internal/connection/InternalStreamConnection.java

    private <T> T sendAndReceiveInternal(final CommandMessage message, final Decoder<T> decoder,
            final OperationContext operationContext) {
        CommandEventSender commandEventSender;
+        Span tracingSpan = createTracingSpan(message, operationContext);


Consider pushing all the changes made to this class down into LoggingCommandEventSender, which already contains a lot of similar logic. LoggingCommandEventSender might need some refactoring as a result, but it seems better than messing too much with this class, which already has enough responsibilities as it is.

mp911de · 2025-08-06T14:03:35Z

Paging @jonatan-ivanov

jonatan-ivanov · 2025-08-06T19:18:50Z

Hi,

I'm one of the Maintainers of Micrometer and Micrometer Tracing.
I'm happy you want to use the Tracing API! I can share some feedback on this PR if you would like to receive some.

I think the most important feedback I'd like to give is recommending to use the Observation API instead of "just" the Tracing API. The reason behind it is that this PR adds tracing capabilities but if you also want to add metrics support, this needs to be instrumented again. Also if users want (custom) logs or any custom output that they can figure out based on the instrumentation in these components, that also need to happen through a separate mechanism.
The idea behind the Observation API, is to put these Observability needs behind one API so that you need to instrument your components once and you can get any output you like from that instrumentation (tracing, metrics, logs, anything that your users can come up with) without modifying the instrumentation itself.
The usage of it is similar to the Tracing API so what you already instrumented should be relatively easy to migrate but it's much more powerful than that and if you register tracing, it will call the Micrometer Tracing API to create spans. The whole Spring Portfolio is instrumented using this API including most of the popular frameworks/libraries.
If you want to learn more, here's a talk here we explain some basics: https://www.youtube.com/watch?v=Qyku6cR6ADY (starts at 14:00 but I recommend watching the whole talk).

Regarding to the Tracing API usage, I think the most important thing I would like to mention is that it is a Tracing Facade. It is what SLF4J is for loggers. As SLF4J can delegate to logging libraries, Micrometer Tracing can delegate to tracing libraries (Brave and OpenTelemetry right now but custom ones can be implemented by users). Because of this, it's usually not needed to pull another facade in front of it (just like it is usually not needed for SLF4J).

Also, the Tracing and Observation APIs provide the features that are implemented here: NOOP, unit test support (spans in-memory), integration test support (with Brave/Zipkin, OTel/OTLP, ...), etc.

The Observation API also has a nice feature that the Tracing API does not and it seems you could benefit from that (based on the Tags class and span names): it has a component called ObservationConvention which lets the MongoDB team define their own convention(s) but the users can define theirs too and decide which one they want to use. So users can use the MongoDB team's convention (default), the OpenTelemetry naming convention, or their company's convention (regardless of which Tracing library is under the hood). You can see this in action in the video I linked above.

jyemin · 2025-08-20T14:59:14Z

Thanks, @jonatan-ivanov. That's very useful context.

Seems like @mp911de commit to the Redis driver is close to what we would need to do here should we choose this route? Then configuration would be similar to this.

mp911de · 2025-08-21T13:29:00Z

Agree with #1695 (comment). I think this is the best way forward to get the most flexibility.

…king with micrometer-tracing directly

jonatan-ivanov · 2025-10-08T18:09:44Z

@jyemin Sorry for the late response.
I think so except I would check if you can use the Observation API directly without directly depending on a tracer.

mp911de · 2025-10-09T08:37:16Z

FTR, you might want to ensure that your implementation isn't prone to the bug we fixed at spring-projects/spring-data-mongodb#5067

nhachicha self-assigned this Apr 29, 2025

rozza reviewed May 1, 2025

View reviewed changes

driver-core/src/main/com/mongodb/tracing/MicrometerTracer.java Outdated Show resolved Hide resolved

nhachicha mentioned this pull request Jul 7, 2025

Added operation (aka command name) to structured logging #1758

Merged

nhachicha force-pushed the JAVA-5733 branch 3 times, most recently from de23d90 to 8e9d2b2 Compare July 20, 2025 22:38

nhachicha marked this pull request as ready for review July 21, 2025 00:27

nhachicha requested a review from a team as a code owner July 21, 2025 00:27

nhachicha requested review from NathanQingyangXu, rozza, vbabanin and Copilot and removed request for a team and NathanQingyangXu July 21, 2025 00:27

Copilot AI reviewed Jul 21, 2025

View reviewed changes

rozza requested changes Jul 22, 2025

View reviewed changes

jyemin requested changes Jul 23, 2025

View reviewed changes

nhachicha added 3 commits August 3, 2025 17:56

Add tracing support using Micrometer

f650d43

Simplifying bookkeeping logic for Span grouping

4a16c29

Merging back missing changes after rebase

33d46e8

nhachicha force-pushed the JAVA-5733 branch from 8e9d2b2 to 33d46e8 Compare August 4, 2025 12:14

nhachicha added 2 commits August 5, 2025 00:27

Fixing tests

86f1791

Merge remote-tracking branch 'origin/main' into JAVA-5733

050fb60

nhachicha added 2 commits August 10, 2025 18:33

Adding method to get namespace for Read and Write Operations

da3ac32

Refactoring operations and command spans

1a75290

nhachicha mentioned this pull request Sep 11, 2025

DRIVERS-719 OpenTelemetry specification mongodb/specifications#1826

Merged

5 tasks

nhachicha added 6 commits October 2, 2025 15:14

Refactor the tracing implementation to use Observation instead of wor…

26cc57a

…king with micrometer-tracing directly

Added Prose Tests

45f3cb8

Fixing test dependencies

39483e4

Skipping non-compliant tests

0ecfb19

Merge remote-tracking branch 'origin/main' into JAVA-5733

0523d41

Fixing test deps for Scala

fb1f1af

nhachicha requested a review from rozza October 8, 2025 14:33

Refactored some type visibility per PR feedback

0628386

Fixing javadoc & Scala test

d3f2d62

using JVM option behind a flag

c490154

	if (!reportedNode.getName().equalsIgnoreCase(expectedNode.getName())) {
	if (!reportedNode.getName().equals(expectedNode.getName())) {

Add tracing support using Micrometer #1695

Are you sure you want to change the base?

Add tracing support using Micrometer #1695

Uh oh!

Conversation

nhachicha commented Apr 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rozza left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Copilot AI Jul 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 21, 2025

Choose a reason for hiding this comment

Uh oh!

rozza left a comment

Choose a reason for hiding this comment

Uh oh!

rozza Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jyemin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jyemin Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

nhachicha Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jyemin Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

mp911de commented Aug 6, 2025

Uh oh!

jonatan-ivanov commented Aug 6, 2025

Uh oh!

jyemin commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mp911de commented Aug 21, 2025

Uh oh!

jonatan-ivanov commented Oct 8, 2025

Uh oh!

mp911de commented Oct 9, 2025

Uh oh!

Uh oh!

nhachicha commented Apr 29, 2025 •

edited

Loading

rozza left a comment •

edited

Loading

jyemin commented Aug 20, 2025 •

edited

Loading